Sprite 1984 - 1993/Sprite 1984 - 1993.iso/man/cmds/tx.man

Text File | 1990-08-11 | 18.3 KB | 464 lines

'\" Copyright 1989 Regents of the University of California
'\" Permission to use, copy, modify, and distribute this
'\" documentation for any purpose and without fee is hereby
'\" granted, provided that this notice appears in all copies.
'\" The University of California makes no representations about
'\" the suitability of this material for any purpose.  It is
'\" provided "as is" without express or implied warranty.
'\"
'\" $Header: /sprite/src/cmds/tx/RCS/tx.man,v 1.15 90/08/10 17:50:20 shirriff Exp $ SPRITE (Berkeley)
'
.so \*(]ltmac.sprite
.HS TX cmds
.BS
.SH NAME
tx \- Scrollable terminal emulator for X
.SH SYNOPSIS
\fBtx \fR[\fIoptions\fR]
.SH OPTIONS
.IP "\fB\-bd \fIcolor\fR" 15
Use \fIcolor\fR as the border color for the window.  If this switch
isn't given then the \fBborderColor\fR X default is used.  If it isn't given
either, then the foreground color is used.
.IP "\fB\-bg \fIcolor\fR" 15
Use \fIcolor\fR as the background color for the window.  If this switch
isn't given then the \fBbackground\fR X default is used.  If it isn't given
either, or if the display is a black-and-white one, then White is used.
.IP "\fB\-D\fR" 15
.VS
Causes \fBtx\fR not to detach itself from its parent process.
.IP "\fB\-display \fIhost\fB:\fIdisplay\fR" 15
.VS
Use \fIhost\fR and \fIdisplay\fR as an indication of the
display on which to open the window.  The display defaults to the
one specified in the \fBDISPLAY\fR environment variable.
.VE
.IP "\fB\-fg \fIcolor\fR" 15
Use \fIcolor\fR as the foreground color for the window.  If this switch
isn't given then the \fBforeground\fR X default is used.  If it isn't given
either, or if the display is a black-and-white one, then Black is used.
.IP "\fB\-fn \fIfont\fR" 15
Use \fIfont\fR as the font for the window.  If this switch isn't given,
then the \fBfont\fR X default is used as the font.  If it isn't given
either, then the Sx default font is used.
.IP "\fB\-geometry \fIgeometry\fR" 15
.VS
Use \fIgeometry\fR as the geometry for the window.  If no geometry
is specified on the command line, it the geometry defaults to the value of the
\fBgeometry\fR X default.  If no default is specified, then
\fBtx\fR picks a geometry.
.IP \fB\-help\fR
Print out a list of the command-line options (and brief descriptions
of their functions) and exit without opening a window.
.VE
.IP "\fB\-icon \fIfile\fR" 15
\fIFile\fR is the name of a file in bitmap format.  Read the file and
use it as the icon for the window.  If \fIfile\fR is \fBlocalhost\fR,
then \fBtx\fR chooses the default icon file corresponding to the local host.
.IP "\fB\-ix \fIxcoord\fR" 15
Display the icon at x-coordinate \fIxcoord\fR.
.IP "\fB\-iy \fIycoord\fR" 15
Display the icon at y-coordinate \fIycoord\fR.
.IP "\fB\-sb \fIcolor\fR" 15
Use \fIcolor\fR as the background color for the window's scrollbar.
If this switch isn't given then the \fBscrollbar.background\fR
X default is used.  If it isn't given either, then the background
color for the text window is used.
.IP "\fB\-se \fIcolor\fR" 15
Use \fIcolor\fR as the color for the window's scrollbar elevator.
If this switch isn't given then the \fBscrollbar.elevator\fR
X default is used.  If it isn't given either, then the background
color for the text window is used.
.IP "\fB\-sf \fIcolor\fR" 15
Use \fIcolor\fR as the foreground color for the window's scrollbar.
If this switch isn't given then the \fBscrollbar.foreground\fR
X default is used.  If it isn't given either, then the foreground
color for the text window is used.
.IP "\fB\-showtitle\fR" 15
.VS
Display a title bar at the top of the window.  Tx normally assumes
that a window manager will display a title bar;  if your window
manager doesn't, you may wish to use this switch.  If this switch
isn't specified, then Tx checks for a \fBshowTitle\fR X default;
if it exists and contains the string ``yes'', then a title
bar will be displayed.
.VE
.IP "\fB\-tb \fIcolor\fR" 15
Use \fIcolor\fR as the background color for the window's title bar.
If this switch isn't given then the \fBtitle.background\fR
X default is used.  If it isn't given either, then the background
color for the text window is used.  This option is ignored if
Tx isn't displaying a title bar.
.IP "\fB\-tf \fIcolor\fR" 15
Use \fIcolor\fR as the foreground color for the window's title bar.
If this switch isn't given then the \fBtitle.foreground\fR
X default is used.  If it isn't given either, then the foreground
color for the text window is used.  This option is ignored if
Tx isn't displaying a title bar.
.IP "\fB\-ts \fIcolor\fR" 15
Use \fIcolor\fR as the color for the window's title stripes.
If this switch isn't given then the \title.stripe\fR
X default is used.  If it isn't given either, then the foreground
color for the text window is used.  This option is ignored if
Tx isn't displaying a title bar.
.IP "\fB\-title \fIname\fR" 15
Display \fIname\fR in the title bar for the window.  The default title
is the name of the pseudo-terminal associated with the window.
.IP "\fB=\fIgeometry\fR" 15
Use \fIgeometry\fR as the geometry specifier for the window (same effect
as the \fB\-geometry option).
.IP "\fIhost:display\fR" 15
Use this argument to select the display on which to create the window
(same effect as the \fB\-display\fR option).
.IP "\fB\-e \fIcommand\fP" 15
This switch must be the last one, if it is present.  The arguments following
the \fB\-e\fR switch constitute
the command to execute in the window.
\fICommand\fR is run using the terminal emulator for
standard input and standard output.  When the command completes, the window
will be destroyed and \fBtx\fR will exit.  The default command is ``/bin/csh -i'',
or if a SHELL environment variable is defined, then it is invoked with a -i
argument.
.BE
.SH INTRODUCTION
\fBTx\fR is a terminal emulator that uses the facilities of the X window
system, the Sx supplementary library, and the Tcl command interpreter.
It executes a command
(usually a shell) and arranges for the command's standard input and
standard output streams to be directed from/to a pseudo-terminal controlled
by \fBtx\fR.  \fBTx\fR, in turn, displays a scrollable window in more-or-less the
same way as \fBmx\fR;  output from the application is displayed in the window
and keystrokes typed in the window are passed through to the application.
\fBTx\fR windows emulate a very simple terminal with enough facilities to run
programs like vi.
.LP
The implementation of \fBtx\fR is very similar to that of \fBmx\fR;  it shares
much of the code and many of the commands.  You should read the \fBmx\fR
manual page before reading this one, in order to learn about the basic
command interface and the \fBmx\fR commands.  \fBTx\fR commands that are identical
to \fBmx\fR commands are not documented here except by reference to the \fBmx\fR
manual page.

.SH ".TX FILES"
After processing command line options and opening the window,
\fBtx\fR checks for the existence of a file ``.tx'' in your
home directory (environment variable HOME).  If the file exists, \fBtx\fR
reads it in and processes it as a command file, just as if it were read
with the \fBsource\fP command.  Then it checks for a .tx file in the
current directory, and processes it if it exists.

.SH SELECTION
Selection in \fBtx\fR is identical to that in \fBmx\fR, except for one difference.
In \fBtx\fR the caret always appears at the end of the typescript, except
when the typescript is in vi mode (see the \fBvi\fR command);  there
is no way to reposition the caret with the mouse.

.SH "VARIABLES"
See the \fBmx\fR manual page for overall information.  The special
variables defined by \fBtx\fR are:
.RS
.TP
\fBargs\fP
Set by \fBtx\fR to hold the arguments to the current variable being executed, if any.
.TP
\fBheight\fP
Set by \fBtx\fR to hold the
height of the window, in lines of text.  If the last line
appearing in the window is only partially visible, it doesn't count.
.TP
\fBsearchCmd\fP
When the middle button is clicked in the ``Search'' string entry, or when
carriage-return is typed there, the contents of this variable are
executed as a command.
.TP
\fBsearchString\fP
Set by \fBtx\fR to hold the contents of the search entry subwindow.
.TP
\fBtermcap\fP
Set by \fBtx\fR to hold a
termcap entry that provides enough functionality to run Vi and other
prehistoric screen-based programs.  It's based on a terminal type ``tx''.
This variable is automatically reset whenever the window changes size.
.TP
\fBversion\fR
.VS
Set by \fBtx\fR to hold a version number in the form \fIx.y\fR, where
changes in \fIx\fR correspond to major revisions with probable
incompatibilities, and changes in \fIy\fR represent small bug fixes
and upgrades that should not cause substantial compatibility problems.
.VE
.TP
\fBwidth\fP
Set by \fBtx\fR to hold the
width of the window, in characters.  If the last character position
is only partially-visible, then it doesn't count.  If a variable-width
font is being used, the average character size is used in computing
the window's width.
.TP
\fBwindowId\fR
Set by \fBtx\fR to hold the X window identifier for this window.
.RE

.SH "MARKS"
See the \fBmx\fR manual page for documentation.  The same special marks are
defined in \fBtx\fR as in \fBmx\fR.

.SH "COMMANDS"
\fBTx\fR is based around the Tcl interpreter just as \fBmx\fR is.  Each keystroke
or menu selection is bound to a Tcl command string, which is passed to
the Tcl interpreter for execution.  See the Tcl man page for details
on the built-in commands provided by Tcl.  In addition to them, \fBtx\fR
provides the following additional built-in commands.  Many of them
are identical to the corresponding commands in \fBmx\fR.
.TP
\fBbind \fR[\fIsequence\fR [\fIcommand\fR]]
Same as in \fBmx\fR.
.TP
\fBcaret \fIoperand\fR
Same as in \fBmx\fR.
.TP
\fBcontrol \fIoption string\fR
.VS
Same as in \fBmx\fR.
.VE
.TP
\fBdelete\fI mark1 \fR[\fImark2\fR]
Same as in \fBmx\fR.
.TP
\fBescape \fIoption\fR\fR
If \fIoption\fR is \fBon\fR, this command enables escape sequences
in window output:  whenever \fBtx\fR finds an escape character (33\s-2\d8\u\s+2)
in the stream of characters output to the pseudo-device for display in
the window, it discards the escape sequence and interprets
the following characters (up to and including the next newline character)
as a \fBtx\fR command rather than characters to be displayed in the window.
If \fIoption\fR is \fBoff\fR, escape sequences are disabled:  they will
be output to the window just like any other characters.  Escape sequences
are enabled by default in \fBtx\fR, and must be enabled for the TERMCAP mechanisms
to work.  This command is most useful to temporarily disable escape-processing
while running programs that generate meaningless escape sequences.
.TP
\fBextract\fI mark1 \fR[\fImark2\fR]
Same as in \fBmx\fR.
.TP
\fBfocus \fIwindow \fR[\fBclear\fR]
Same as in \fBmx\fR.
.TP
\fBgeometry \fIspec\fR
Same as in \fBmx\fR.
.TP
\fBinsert\fR \fIbytes\fR \fIbytes\fR ...
Send \fIbytes\fR to the application as keyboard input on the pty.  If
more than one \fIbytes\fR argument is supplied, each is input in turn,
with a single space between them.
.TP
\fBmark\fI src op args\fR
Same as in \fBmx\fR.
.TP
\fBmenu\fI option args\fR
Same as in \fBmx\fR.
.TP
\fBmessage\fI string\fR
Same as in \fBmx\fR.
.TP
\fBmxopen \fR[\fIoptions\fR] \fIfile file ...\fR
.VS
Same as \fBopen\fR command in in \fBmx\fR.  Used to create an \fBmx\fR
window from \fBtx\fR, e.g. to display variable values.
.TP
\fBmxsend \fIwindow command\fR
Same as in \fBsend\fR command in \fBmx\fR.  Used to send commands to
\fBmx\fR windows created from \fBtx\fR.
.VE
.TP
\fBopen\fR [\fIoptions\fR]
.VS
Open a new \fBtx\fR window.  The \fIoptions\fR to this command are exactly
the same as the command-line options for the \fBtx\fR program, with
the following exceptions.  If the \fB\-e\fR switch is given, then
a new typescript is
created and all the remaining arguments to \fBopen\fR are used as a
command name and arguments for the top-level application in
the new typescript.  If the \fB\-e\fR option is not given, then the new
window will provide an alternate view on the same typescript as the
invoking window.  The \fB\-D\fR
option is not permitted, nor are options that specify a display.
If no geometry specification is given in
\fIoptions\fR, then \fBtx\fR uses the contents of the global variable
\fBgeometry\fP as a default geometry;  if no \fBgeometry\fP variable
exists, then \fBtx\fR picks a default geometry.
Other options, such
as foreground color and font, default to the values from the invoking
window, rather than looking for X defaults.
.VE
\fBOpen\fR sets the global variable \fBnewWindow\fR
to hold the id of the newly-created window.  This may be used in
conjunction with the \fBsend\fR command to issue commands to the
new window.  The return value is always an empty string.
.TP
\fBoutput \fIbytes\fR
Insert \fIbytes\fR in the output display as if they had been output
by the application.
.TP
\fBquit\fR
Destroy the \fBtx\fR window and end the program.
.TP
\fBquote\fR
.VS
Same as in \fBmx\fR.
.VE
.TP
\fBsearch \fR[\fIdirection \fR[\fIpattern\fR]]
Same as in \fBmx\fR.
.TP
\fBsee \fImark\fP [\fBtop\fR|\fBcenter\fR|\fBbottom\fR]
Same as in \fBmx\fR.
.TP
\fBselection \fIoption \fR[\fIarg ...\fR]
Same as in \fBmx\fR.
.TP
\fBsend \fIwindow command\fR
Same as in \fBmx\fR.
.TP
\fBtitle \fIleft center right wmName\fR
.VS
Change the title information for the window.  \fILeft\fR will be
displayed at the left side of the title bar, \fIcenter\fR in the
middle of the bar, and \fIright\fR at the right side of the title
bar.  If any of these three arguments is an empty string, then
nothing will be displayed in the corresponding position.  The
string given by \fIwmName\fR will be recorded as the window's
name for the window manager.  This name will probably appear when
the window is iconified, for example.  If Tx isn't displaying a title
for the window, then only the \fIwmName\fR argument will be used.
.VE
.TP
\fBupdate\fR
Same as in \fBmx\fR.
.TP
\fBvi \fIoption args\fR
This command provides an alternate mode of operation, called ``vi mode'',
which provides sufficient terminal emulation to run the vi editor.  When
the window is in vi mode, an additional window-full of blank lines  (called
the \fIvi area\fR) is
added at the beginning (top) of the typescript, and the view is shifted
to display those lines.  Most of the \fBvi\fR commands are used only
in the crude termcap entry that \fBtx\fR provides for itself.  The
\fBvi\fR command must have one of the following forms:
.RS
.TP
\fBvi enter\fR
Enter vi mode.  Fill the vi area with blank lines, change the window's
view to display those lines, and move the caret to position 0.0.
.TP
\fBvi leave\fR
Leave vi mode.  Delete the lines in the vi area,
move the caret back to the end of the typescript, and change the window's
view to display the end of the typescript.
.TP
\fBvi cd\fR
Clear all the lines on the screen at or below the caret position, leaving
the caret at the beginning of its (now-blank) line.  This command is
provided primarily for emulating the \fBcd\fR termcap entry.
.TP
\fBvi ce\fR
Clear from the caret position to the end of the line, leaving the caret
where it is.  This command is provided primarily for emulating the \fBce\fR
termcap entry.
.TP
\fBvi clear\fR
Clear the lines in the vi area and move the caret to the home position
(0.0).
.TP
\fBvi cursor\fI lineIndex charIndex\fR
Set the caret position to line \fIlineIndex\fR, character \fIcharIndex\fR.
This position must lie within the via area.
.TP
\fBvi deleteline\fR
Delete the line containing the caret, and add a new line to the bottom
of the vi area to keep the total number of lines in the via area constant.
.TP
\fBvi insertline\fR
Add a new blank line to the vi area, just before the caret (the caret
should be at the beginning of a line).  Delete the last line in the vi
area, in order to keep the total number of lines in the vi area constant.
.TP
\fBvi on\fR
Returns a non-zero string if the window is currently in vi mode,
and a zero string otherwise.
.TP
\fBvi tab\fR
Move the caret to the next tab stop.
.TP
\fBvi up\fR
Move the caret up one line.
.TP
\fBvi vt100 \fImode\fR
.VS
If mode is nonzero, tx enters vt100 emulation mode.  If mode is zero,
tx exits vt100 emulation mode.  Not all vt100 functions are emulated.
.VE
.RE

.SH "COMMAND PROCEDURES"
.VS
In addition to the built-in commands described above, a number of Tcl
command procedures are created by the default \fBtx\fR startup file.  They
may be invoked just like built-in commands, and are described below.
.TP
\fBshowBindings \fIbinding binding ...\fR
Same as in \fBmx\fR.
.TP
\fBshowMenus \fIname name ...\fR
Same as in \fBmx\fR.
.TP
\fBshowProcs \fIname name ...\fR
Same as in \fBmx\fR.
.TP
\fBshowVars \fIname name ...\fR
Same as in \fBmx\fR.
.TP
\fBwhere\fR
Same as in \fBmx\fR.
.VE

.SH "TERMCAP INFORMATION"
\fBTx\fR stores an up-to-date termcap entry in the \fBtermcap\fR variable, and
initializes the TERM and TERMCAP environment variables when it
starts up, so that
you can run programs that use termcap information.  If you change the
size of a \fBtx\fR window, \fBtx\fR will update the \fBtermcap\fR variable
and invoke the TIOCSWINSZ ioctl to notify the application, but
it cannot update the TERM and TERMCAP environment variables in the
application;  you can use the ``Set Termcap'' menu entry to invoke
shell commands to update TERM and TERMCAP.
If you use \fBtx\fR to rlogin to a different machine, most machines
have never heard of \fBtx\fR so they don't have entries for it in their
/etc/termcap files.  There are two possible solutions to this problem:
a) you can invoke the ``Set Termcap'' menu entry after you've gotten
logged in to the remote machine;  b) you can use the \fItxinfo\fR
program as part of your .login shell script, in order to set up the
TERMCAP automatically.  See the manual page for \fItxinfo\fR for
details.

.SH "COMMAND SUBWINDOW"
Same as in \fBmx\fR.

.SH "MULTIPLE WINDOWS ON SAME TYPESCRIPT"
The \fBopen\fR command may be used to open several windows on the
same typescript.  The windows behave identically except for
one thing: window size.  There is a single window size associated
with the typescript, which is returned when applications perform
TIOCGWINSZ ioctl operations on the pseudo-terminal.  If the different
windows have different sizes, then Tx always uses the size from
a particular one of the windows (usually the first window created on the
typescript).  The other windows are labelled
\fBAlternate\fR at the right side of their title bars
to indicate that their sizes will not be reflected to the application.

.SH "SEE ALSO"
mx, txcmd, txinfo

.SH KEYWORDS
mouse, terminal emulator, typescript, window